<?php
/** 
 * 
 *
 * @package api
 * @subpackage collections
 * @author $Author$
 * @version $Id: Iterator.php 14 2006-11-28 22:05:19Z rdff3 $
 */
 
/**
 * Interface CollectionIterator
 *
 * An iterator over a collection. CollectionIterator takes the place of Enumeration in the PHP collections framework. 
 * CollectionIterators differ from enumerations in two ways:
 * <ul>
 * <li>CollectionIterators allow the caller to remove elements from the underlying collection during the iteration with well-defined semantics.</li>
 * <li>Method names have been improved. </li>
 * </ul>
 *
 * This interface is a member of the PHP Collections Framework. 
 * 
 * @package api
 * @subpackage collections
 * @author $Author$
 * @version $Id: Iterator.php 14 2006-11-28 22:05:19Z rdff3 $
 */
interface CollectionIterator extends Iterator {
	/**
	 * Returns true if the iteration has more elements
	 *
	 * Returns true if the iteration has more elements.  (In other words, returns true if {@link next} would return an element 
	 * rather than throwing and exception.)
	 *
	 * @returns boolean true if the iterator has more elements
	 */
	public function hasNext();
	
	/**
	 * Returns the next element in the iteration.
	 *
	 * Returns the next element in the iteration.  Calling this method repeatedly until the {@link hasNext} method returns false will
	 * return each element in the underlying collection exactly once.
	 *
	 * @returns Object the next element in the iteration
	 * @throws {@link NoSuchElementException} - iterator has no more elements
	 */
	public function getNext();
	
	
	
	/**
	 * Removes from the underlying collection the last element returned by the iterator (optional operation). 
	 * 
	 * This method can be called only once per call to {@link next}. The behavior of an iterator is unspecified if the 
	 * underlying collection is modified while the iteration is in progress in any way other than by calling this method.
	 * 
	 * @throws {@link UnsupportedOperationException} - if the {@link remove} operation is not supported by this {@link CollectionIterator}.
	 * @throws {@link IllegalStateException} - if the {@link next} method has not yet been called, or the {@link remove} 
	 * 		method has already been called after the last call to the {@link next} method.
	 */
	public function remove();
}


?>